<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: Paperclip::Storage::S3</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href="../../.././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">Paperclip::Storage::S3</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../../../files/vendor/plugins/paperclip/lib/paperclip/storage_rb.html">
                vendor/plugins/paperclip/lib/paperclip/storage.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <p>
Amazon&#8216;s <a href="S3.html">S3</a> file hosting service is a scalable,
easy place to store files for distribution. You can find out more about it
at <a href="http://aws.amazon.com/s3">aws.amazon.com/s3</a> There are a few
<a href="S3.html">S3</a>-specific options for has_attached_file:
</p>
<ul>
<li>+s3_credentials+: Takes a path, a File, or a Hash. The path (or File) must
point to a YAML file containing the <tt>access_key_id</tt> and
<tt>secret_access_key</tt> that Amazon gives you. You can
&#8216;environment-space&#8217; this just like you do to your database.yml
file, so different environments can use different accounts:

<pre>
  development:
    access_key_id: 123...
    secret_access_key: 123...
  test:
    access_key_id: abc...
    secret_access_key: abc...
  production:
    access_key_id: 456...
    secret_access_key: 456...
</pre>
<p>
This is not required, however, and the file may simply look like this:
</p>
<pre>
  access_key_id: 456...
  secret_access_key: 456...
</pre>
<p>
In which case, those access keys will be used in all environments. You can
also put your bucket name in this file, instead of adding it to the code
directly. This is useful when you want the same account but a different
bucket for development versus production.
</p>
</li>
<li>+s3_permissions+: This is a String that should be one of the
&quot;canned&quot; access policies that <a href="S3.html">S3</a> provides
(more information can be found here: <a
href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html#RESTCannedAccessPolicies">docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html#RESTCannedAccessPolicies</a>)
The default for <a href="../../Paperclip.html">Paperclip</a> is
:public_read.

</li>
<li>+<a href="S3.html#M000087">s3_protocol</a>+: The protocol for the URLs
generated to your <a href="S3.html">S3</a> assets. Can be either
&#8216;http&#8217; or &#8216;https&#8217;. Defaults to &#8216;http&#8217;
when your :s3_permissions are :public_read (the default), and
&#8216;https&#8217; when your :s3_permissions are anything else.

</li>
<li>+s3_headers+: A hash of headers such as {&#8216;Expires&#8217; =&gt;
1.year.from_now.httpdate}

</li>
<li><tt>bucket</tt>: This is the name of the <a href="S3.html">S3</a> bucket
that will store your files. Remember that the bucket must be unique across
all of Amazon <a href="S3.html">S3</a>. If the bucket does not exist <a
href="../../Paperclip.html">Paperclip</a> will attempt to create it. The
bucket name will not be interpolated. You can define the bucket as a Proc
if you want to determine it&#8216;s name at runtime. <a
href="../../Paperclip.html">Paperclip</a> will call that Proc with
attachment as the only argument.

</li>
<li>+<a href="S3.html#M000084">s3_host_alias</a>+: The fully-qualified domain
name (FQDN) that is the alias to the <a href="S3.html">S3</a> domain of
your bucket. Used with the :s3_alias_url url interpolation. See the link in
the <tt>url</tt> entry for more information about <a href="S3.html">S3</a>
domains and buckets.

</li>
<li><tt>url</tt>: There are three options for the <a href="S3.html">S3</a> url.
You can choose to have the bucket&#8216;s name placed domain-style
(bucket.s3.amazonaws.com) or path-style (s3.amazonaws.com/bucket). Lastly,
you can specify a CNAME (which requires the CNAME to be specified as
:s3_alias_url. You can read more about CNAMEs and <a href="S3.html">S3</a>
at <a
href="http://docs.amazonwebservices.com/AmazonS3/latest/index.html?VirtualHosting.html">docs.amazonwebservices.com/AmazonS3/latest/index.html?VirtualHosting.html</a>
Normally, this won&#8216;t matter in the slightest and you can leave the
default (which is path-style, or :s3_path_url). But in some cases paths
don&#8216;t work and you need to use the domain-style (:s3_domain_url).
Anything else here will be treated like path-style. NOTE: If you use a
CNAME for use with CloudFront, you can NOT specify https as your :<a
href="S3.html#M000087">s3_protocol</a>; This is *not supported* by <a
href="S3.html">S3</a>/CloudFront. Finally, when using the host alias, the
:bucket parameter is ignored, as the hostname is used as the bucket name by
<a href="S3.html">S3</a>.

</li>
<li><tt>path</tt>: This is the key under the bucket in which the file will be
stored. The URL will be constructed from the bucket and the path. This is
what you will want to interpolate. Keys should be unique, like filenames,
and despite the fact that <a href="S3.html">S3</a> (strictly speaking) does
not support directories, you can still use a / to separate parts of your
file name.

</li>
</ul>

    </div>


   </div>

    <div id="method-list">
      <h3 class="section-bar">Methods</h3>

      <div class="name-list">
      <a href="#M000083">bucket_name</a>&nbsp;&nbsp;
      <a href="#M000086">exists?</a>&nbsp;&nbsp;
      <a href="#M000082">expiring_url</a>&nbsp;&nbsp;
      <a href="#M000081">extended</a>&nbsp;&nbsp;
      <a href="#M000085">parse_credentials</a>&nbsp;&nbsp;
      <a href="#M000084">s3_host_alias</a>&nbsp;&nbsp;
      <a href="#M000087">s3_protocol</a>&nbsp;&nbsp;
      <a href="#M000088">to_file</a>&nbsp;&nbsp;
      </div>
    </div>

  </div>


    <!-- if includes -->

    <div id="section">





      


    <!-- if method_list -->
    <div id="methods">
      <h3 class="section-bar">Public Class methods</h3>

      <div id="method-M000081" class="method-detail">
        <a name="M000081"></a>

        <div class="method-heading">
          <a href="#M000081" class="method-signature">
          <span class="method-name">extended</span><span class="method-args">(base)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000081-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000081-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 129</span>
129:       <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">extended</span> <span class="ruby-identifier">base</span>
130:         <span class="ruby-keyword kw">begin</span>
131:           <span class="ruby-identifier">require</span> <span class="ruby-value str">'aws/s3'</span>
132:         <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">LoadError</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">e</span>
133:           <span class="ruby-identifier">e</span>.<span class="ruby-identifier">message</span> <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-value str">&quot; (You may need to install the aws-s3 gem)&quot;</span>
134:           <span class="ruby-identifier">raise</span> <span class="ruby-identifier">e</span>
135:         <span class="ruby-keyword kw">end</span>
136: 
137:         <span class="ruby-identifier">base</span>.<span class="ruby-identifier">instance_eval</span> <span class="ruby-keyword kw">do</span>
138:           <span class="ruby-ivar">@s3_credentials</span> = <span class="ruby-identifier">parse_credentials</span>(<span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_credentials</span>])
139:           <span class="ruby-ivar">@bucket</span>         = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:bucket</span>]         <span class="ruby-operator">||</span> <span class="ruby-ivar">@s3_credentials</span>[<span class="ruby-identifier">:bucket</span>]
140:           <span class="ruby-ivar">@bucket</span>         = <span class="ruby-ivar">@bucket</span>.<span class="ruby-identifier">call</span>(<span class="ruby-keyword kw">self</span>) <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@bucket</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Proc</span>)
141:           <span class="ruby-ivar">@s3_options</span>     = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_options</span>]     <span class="ruby-operator">||</span> {}
142:           <span class="ruby-ivar">@s3_permissions</span> = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_permissions</span>] <span class="ruby-operator">||</span> <span class="ruby-identifier">:public_read</span>
143:           <span class="ruby-ivar">@s3_protocol</span>    = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_protocol</span>]    <span class="ruby-operator">||</span> (<span class="ruby-ivar">@s3_permissions</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">:public_read</span> <span class="ruby-operator">?</span> <span class="ruby-value str">'http'</span> <span class="ruby-operator">:</span> <span class="ruby-value str">'https'</span>)
144:           <span class="ruby-ivar">@s3_headers</span>     = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_headers</span>]     <span class="ruby-operator">||</span> {}
145:           <span class="ruby-ivar">@s3_host_alias</span>  = <span class="ruby-ivar">@options</span>[<span class="ruby-identifier">:s3_host_alias</span>]
146:           <span class="ruby-ivar">@url</span>            = <span class="ruby-value str">&quot;:s3_path_url&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-ivar">@url</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">match</span>(<span class="ruby-regexp re">/^:s3.*url$/</span>)
147:           <span class="ruby-constant">AWS</span><span class="ruby-operator">::</span><span class="ruby-constant">S3</span><span class="ruby-operator">::</span><span class="ruby-constant">Base</span>.<span class="ruby-identifier">establish_connection!</span>( <span class="ruby-ivar">@s3_options</span>.<span class="ruby-identifier">merge</span>(
148:             <span class="ruby-identifier">:access_key_id</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@s3_credentials</span>[<span class="ruby-identifier">:access_key_id</span>],
149:             <span class="ruby-identifier">:secret_access_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@s3_credentials</span>[<span class="ruby-identifier">:secret_access_key</span>]
150:           ))
151:         <span class="ruby-keyword kw">end</span>
152:         <span class="ruby-constant">Paperclip</span>.<span class="ruby-identifier">interpolates</span>(<span class="ruby-identifier">:s3_alias_url</span>) <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attachment</span>, <span class="ruby-identifier">style</span><span class="ruby-operator">|</span>
153:           <span class="ruby-node">&quot;#{attachment.s3_protocol}://#{attachment.s3_host_alias}/#{attachment.path(style).gsub(%r{^/}, &quot;&quot;)}&quot;</span>
154:         <span class="ruby-keyword kw">end</span>
155:         <span class="ruby-constant">Paperclip</span>.<span class="ruby-identifier">interpolates</span>(<span class="ruby-identifier">:s3_path_url</span>) <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attachment</span>, <span class="ruby-identifier">style</span><span class="ruby-operator">|</span>
156:           <span class="ruby-node">&quot;#{attachment.s3_protocol}://s3.amazonaws.com/#{attachment.bucket_name}/#{attachment.path(style).gsub(%r{^/}, &quot;&quot;)}&quot;</span>
157:         <span class="ruby-keyword kw">end</span>
158:         <span class="ruby-constant">Paperclip</span>.<span class="ruby-identifier">interpolates</span>(<span class="ruby-identifier">:s3_domain_url</span>) <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">attachment</span>, <span class="ruby-identifier">style</span><span class="ruby-operator">|</span>
159:           <span class="ruby-node">&quot;#{attachment.s3_protocol}://#{attachment.bucket_name}.s3.amazonaws.com/#{attachment.path(style).gsub(%r{^/}, &quot;&quot;)}&quot;</span>
160:         <span class="ruby-keyword kw">end</span>
161:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <h3 class="section-bar">Public Instance methods</h3>

      <div id="method-M000083" class="method-detail">
        <a name="M000083"></a>

        <div class="method-heading">
          <a href="#M000083" class="method-signature">
          <span class="method-name">bucket_name</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000083-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000083-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 167</span>
167:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">bucket_name</span>
168:         <span class="ruby-ivar">@bucket</span>
169:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000086" class="method-detail">
        <a name="M000086"></a>

        <div class="method-heading">
          <a href="#M000086" class="method-signature">
          <span class="method-name">exists?</span><span class="method-args">(style = default_style)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000086-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000086-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 180</span>
180:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">exists?</span>(<span class="ruby-identifier">style</span> = <span class="ruby-identifier">default_style</span>)
181:         <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">original_filename</span>
182:           <span class="ruby-constant">AWS</span><span class="ruby-operator">::</span><span class="ruby-constant">S3</span><span class="ruby-operator">::</span><span class="ruby-constant">S3Object</span>.<span class="ruby-identifier">exists?</span>(<span class="ruby-identifier">path</span>(<span class="ruby-identifier">style</span>), <span class="ruby-identifier">bucket_name</span>)
183:         <span class="ruby-keyword kw">else</span>
184:           <span class="ruby-keyword kw">false</span>
185:         <span class="ruby-keyword kw">end</span>
186:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000082" class="method-detail">
        <a name="M000082"></a>

        <div class="method-heading">
          <a href="#M000082" class="method-signature">
          <span class="method-name">expiring_url</span><span class="method-args">(time = 3600)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000082-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000082-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 163</span>
163:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">expiring_url</span>(<span class="ruby-identifier">time</span> = <span class="ruby-value">3600</span>)
164:         <span class="ruby-constant">AWS</span><span class="ruby-operator">::</span><span class="ruby-constant">S3</span><span class="ruby-operator">::</span><span class="ruby-constant">S3Object</span>.<span class="ruby-identifier">url_for</span>(<span class="ruby-identifier">path</span>, <span class="ruby-identifier">bucket_name</span>, <span class="ruby-identifier">:expires_in</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">time</span> )
165:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000085" class="method-detail">
        <a name="M000085"></a>

        <div class="method-heading">
          <a href="#M000085" class="method-signature">
          <span class="method-name">parse_credentials</span><span class="method-args">(creds)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000085-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000085-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 175</span>
175:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">parse_credentials</span> <span class="ruby-identifier">creds</span>
176:         <span class="ruby-identifier">creds</span> = <span class="ruby-identifier">find_credentials</span>(<span class="ruby-identifier">creds</span>).<span class="ruby-identifier">stringify_keys</span>
177:         (<span class="ruby-identifier">creds</span>[<span class="ruby-constant">RAILS_ENV</span>] <span class="ruby-operator">||</span> <span class="ruby-identifier">creds</span>).<span class="ruby-identifier">symbolize_keys</span>
178:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000084" class="method-detail">
        <a name="M000084"></a>

        <div class="method-heading">
          <a href="#M000084" class="method-signature">
          <span class="method-name">s3_host_alias</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000084-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000084-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 171</span>
171:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">s3_host_alias</span>
172:         <span class="ruby-ivar">@s3_host_alias</span>
173:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000087" class="method-detail">
        <a name="M000087"></a>

        <div class="method-heading">
          <a href="#M000087" class="method-signature">
          <span class="method-name">s3_protocol</span><span class="method-args">()</span>
          </a>
        </div>
      
        <div class="method-description">
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000087-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000087-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 188</span>
188:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">s3_protocol</span>
189:         <span class="ruby-ivar">@s3_protocol</span>
190:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>

      <div id="method-M000088" class="method-detail">
        <a name="M000088"></a>

        <div class="method-heading">
          <a href="#M000088" class="method-signature">
          <span class="method-name">to_file</span><span class="method-args">(style = default_style)</span>
          </a>
        </div>
      
        <div class="method-description">
          <p>
Returns representation of the data of the file assigned to the given style,
in the format most representative of the current storage.
</p>
          <p><a class="source-toggle" href="#"
            onclick="toggleCode('M000088-source');return false;">[Source]</a></p>
          <div class="method-source-code" id="M000088-source">
<pre>
     <span class="ruby-comment cmt"># File vendor/plugins/paperclip/lib/paperclip/storage.rb, line 194</span>
194:       <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">to_file</span> <span class="ruby-identifier">style</span> = <span class="ruby-identifier">default_style</span>
195:         <span class="ruby-keyword kw">return</span> <span class="ruby-ivar">@queued_for_write</span>[<span class="ruby-identifier">style</span>] <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@queued_for_write</span>[<span class="ruby-identifier">style</span>]
196:         <span class="ruby-identifier">file</span> = <span class="ruby-constant">Tempfile</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">path</span>(<span class="ruby-identifier">style</span>))
197:         <span class="ruby-identifier">file</span>.<span class="ruby-identifier">write</span>(<span class="ruby-constant">AWS</span><span class="ruby-operator">::</span><span class="ruby-constant">S3</span><span class="ruby-operator">::</span><span class="ruby-constant">S3Object</span>.<span class="ruby-identifier">value</span>(<span class="ruby-identifier">path</span>(<span class="ruby-identifier">style</span>), <span class="ruby-identifier">bucket_name</span>))
198:         <span class="ruby-identifier">file</span>.<span class="ruby-identifier">rewind</span>
199:         <span class="ruby-keyword kw">return</span> <span class="ruby-identifier">file</span>
200:       <span class="ruby-keyword kw">end</span>
</pre>
          </div>
        </div>
      </div>


    </div>


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>